home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_amanda.idb / usr / freeware / doc / amanda / INDEXING.z / INDEXING
Encoding:
Text File  |  1999-07-16  |  13.4 KB  |  421 lines
  1. AMINDEX
  2. =======
  3.  
  4.  
  5. Amindex was a collection of code that added dump indexing and more
  6. friendly recovery to amanda-2.3.0.  It has since been fully integrated
  7. into amanda-2.3.0.X.  An index of the files in each dump image is
  8. generated as part of the dump process and stored in a database.  A
  9. tool, amrecover, is provided which lets users browse the database.
  10. Once a set of files to recover has been assembled, amrecover
  11. "automates" the restoration of these files.
  12.  
  13. This file describes how the index files are generated and how amrecover
  14. is used.
  15.  
  16.  
  17. Database Format
  18. ---------------
  19.  
  20. The database consists of a directory containing a large number of
  21. files, one for each disk backup.  The file names are formed from the
  22. host name, disk name, date, and dump level.  The files are ASCII text
  23. files containing a list of the leaf nodes of the dump, one per line.
  24. Each entry is the filename relative to the mount point, starting with a
  25. /, e.g., /home/user1/data from the disk mounted on /home would generate
  26. the entry /user1/data.  The index files are stored in compressed format
  27. (eg gzip or compress).
  28.  
  29.  
  30. Database Record Generation
  31. --------------------------
  32.  
  33. This section walks through the operation of the system while backups
  34. are being done, and highlights the changes to amanda-2.3.0.X needed.
  35.  
  36. First off, a new disk-type option "index" was added.  This required
  37. changes to common-src/conffile.[ch] to parse such an option and add it
  38. to the data structure for options, and changes to server-src/driverio.c
  39. to add "index" to the reconstructed option string passed to clients.
  40. Obviously, a backup index is only generated if this option is added to
  41. a file.
  42.  
  43. On the client side, sendbackup-common.[ch] and sendbackup-dump.c have
  44. been modified to handle the "index" option.  If this option is set,
  45. sendbackup-dump adds createindex-dump to the chain of programs to be
  46. run, between the dump and the compression (if present).
  47. Createindex-dump is responsible for generating the index file.  It
  48. pipes the dump output through "restore -t" to get the necessary
  49. information.  The file is then compressed and stored in a temporary
  50. file on the client.  The location of this file is configurable, e.g.,
  51. /var/tmp, /usr/tmp, /tmp.
  52.  
  53. [ Yes, okay, this makes the file system containing the temp file active
  54. during its dump, which is a bad thing, but if you have the DEBUG flags
  55. set, amanda is also actively using files in /tmp. ]
  56.  
  57. Once all of the dumping operations of amdump have been completed,
  58. amdump calls amgetidx, which determines for which file systems an index
  59. was generated and copies them to the database server (assumed to be the
  60. machine running amdump).  The source for this is in
  61. server-src/amgetidx.c.  In early versions, amgetidx used rsh/rcp to
  62. perform this, but now it uses amandad.
  63.  
  64.  
  65. Database Browsing
  66. -----------------
  67.  
  68. The client is called amrecover and is loosely based on the
  69. functionality of the program "recover" from Backup Copilot.  A user
  70. starts up amrecover.  This requires specifying the index server and the
  71. amanda config name (defaults for both are compiled in as part of the
  72. installation).  Then the user has to specify the name of the host
  73. information is wanted about, the disk name, and (optionally) the disk
  74. mount point.  Finally a date needs to be specified.  Given all this,
  75. the user can then roam around a virtual file system using "ls" and "cd"
  76. much like in a FTP client.  The file system contains all files backed
  77. up on the specified date, or before that date, back to the last level 0
  78. backup.  Only the most recent version of any file is shown.
  79.  
  80. As the file system is traversed, the user can add and delete files to a
  81. "shopping list", and print the list out.
  82.  
  83.  
  84. File Extraction
  85. ---------------
  86.  
  87. When a user has built up a list of files to extract, they can be
  88. extracted by issuing the command "extract" within amrecover.
  89.  
  90. Files are extracted by the following, for each different tape needed.
  91.  
  92. As part of the installation, a "tape server" daemon amidxtaped is
  93. installed on one or more designated hosts, which have an attached tape
  94. drive.  This is used to read the tapes.  See the config files for the
  95. options for specifying a default.
  96.  
  97. Amrecover contacts amidxtaped on the tape server host specifying which
  98. tape device to use, which host and disk files are needed for.  On the
  99. tape server host, amidxtaped exec's amrestore to get the dump image
  100. file off the tape, strips the (amanda) header, and returns the data to
  101. amrecover.
  102.  
  103. If dumps are stored compressed for the client, then amrecover pipes the
  104. data through the appropriate uncompression routine to uncompress it
  105. before piping it into restore, which then extracts the required files
  106. from the dump image.
  107.  
  108. Note that a user can only extract files from a host running the same
  109. operating system as he/she is executing amrecover on, since the native
  110. dump/restore tools are used - unless gnutar is used.
  111.  
  112.  
  113. Protocol Between amindexd and amrecover
  114. ---------------------------------------
  115.  
  116. The protocol talked between amindexd and amrecover is a simple ASCII
  117. chat protocol based on that used in FTP.  Amrecover sends a 1 line
  118. command, and amindexd replies with a 1 line or multi-line reply.  Each
  119. line of the reply starts with a three digit code, starting with a '5'
  120. if an error occurred.  For 1 line replies, and the last line of a
  121. multi-line reply, the 4th character is a space.  For all but the last
  122. line of a multi-line reply, the 4th character is a '-'.
  123.  
  124. The commands and replies other than acknowledgments are:
  125.  
  126. QUIT - finish up and close connection
  127.  
  128. HOST <host> - set host to host
  129.  
  130. DISK <disk> - set disk to disk
  131.  
  132. SCNF <config> - set amanda configuration to config
  133.  
  134. DATE <date> - set date to date
  135.  
  136. DHST - return dump history of current disk
  137.  
  138. OISD <dir> - Opaque is directory? query.  Is the directory <dir>
  139.          present in the backups of the current disk back to and
  140.          including the last level 0 dump.
  141.  
  142. OLSD <dir> - Opaque list directory.  Give all filenames present in
  143.          <dir> in the backups of the current disk back to and
  144.          including the last level 0 dump.
  145.  
  146. ORLD <dir> - Opaque recursive list directory.  Give all filenames 
  147.          present in <dir> and subdir in the backups of the current
  148.          disk back to and including the last level 0 dump.
  149.  
  150. TAPE - return value of tapedev from amanda.conf if set.
  151.  
  152. DCMP - returns "YES" if dumps for disk are compressed, "NO" if dumps
  153.          aren't.
  154.  
  155.  
  156.  
  157. INSTALLATION NOTES
  158. ------------------
  159.  
  160.  
  161. 1) Whether or not an index is created for a disk is controlled by a
  162. disk configuration option "index".  So, in amanda.conf you need to
  163. define a disktype with this option, e.g.,
  164.  
  165. define dumptype comp-user-index {
  166.     comment "Non-root partitions on reasonably fast machines"
  167.     compress client fast
  168.     index yes
  169.     priority medium
  170. }
  171.  
  172. 2) You need to define disks that you want to generate an index for to
  173. be of one of the disktypes you defined which contain the index option.
  174. This cause sendbackup-dump on the client machine to generate an index
  175. file which is stored local to the client, for later recovery by
  176. amgetidx (which is called by amdump).
  177.  
  178. 3) Amanda saves all the index files under a directory specified by
  179. "indexdir" in amanda.conf.  You need to create this directory by hand.
  180. It needs to have read/write permissions set for the user you defined
  181. to run Amanda.
  182.  
  183. If you are using the "text database" option you may set indexdir and
  184. infofile to be the same directory.
  185.  
  186. 4) The index browser, amrecover, currently gets installed as part of
  187. the client software.  Its location may not be appropriate for your
  188. system and you may need to move it to a more accessible place such as
  189. /usr/local/bin.  See its man page for how to use it.
  190.  
  191.  
  192. Note that amindexd, amgetidx, amidxtaped, and amtrmidx all write debug
  193. files on the server in /tmp (unless this feature is disabled in the
  194. source code), which are useful for diagnosing problems.  Amrecover
  195. writes a debug file in /tmp on the machine it is invoked.
  196.  
  197.  
  198. PERMISSIONS
  199. -----------
  200.  
  201. The userid chosen to run the amanda client code must have permission to
  202. run restore since this is used by createindex-dump to generate the
  203. index files.
  204.  
  205. For a user to be able to restore files from within amrecover, that user
  206. must have permission to run restore.
  207.  
  208.  
  209. CHANGES FROM AMINDEX-1.0
  210. ------------------------
  211.  
  212. Get index directory from amanda.conf
  213.  
  214. Integration into amanda-2.3.0.4.
  215.  
  216. Rewriting of amgetidx to use amandad instead of using rsh/rcp.
  217.  
  218.  
  219.  
  220. CHANGES FROM AMINDEX-0.3
  221. ------------------------
  222.  
  223. Support for index generation using gnutar
  224.  
  225. Support for restoring files from within amrecover.
  226.  
  227. Bug fixes:
  228.  
  229.     * index/client/amrecover.c (guess_disk): 
  230.     Removed inclusion of mntent.h and use of MAXMNTSTR since this
  231.     was non-portable, as pointed out by Izzy Ergas
  232.     <erga00@nbhd.org>.
  233.  
  234.     * index/client/display_commands.c (list_directory): 
  235.     Removed point where list_directory() could sleep for ever
  236.     waiting for input that wasn't going to come.
  237.  
  238.     * index/server/amindexd.c
  239.       index/client/uscan.l
  240.     Installed patches from Les Gondor <les@trigraph.on.ca> to make
  241.     amrecover handle spaces in file names.
  242.  
  243.     * server-src/amcontrol.sh: 
  244.     As pointed out by Neal Becker <neal@ctd.comsat.com> there were
  245.     still a few sh-style comments that needed conversion to
  246.     c-style.
  247.  
  248.  
  249.  
  250.  
  251. CHANGES FROM AMINDEX-0.2
  252. ------------------------
  253.  
  254.     * index/client/Makefile.in
  255.     * index/client/help.c
  256.     * index/client/amrecover.h
  257.     * index/client/uparse.y
  258.     * index/client/uscan.l
  259.     Added a help command.
  260.  
  261.     * index/client/set_commands.c:
  262.     set_disk() and set_host() now check for empty extract list.
  263.     
  264.     * index/client/extract_list.c:
  265.     * index/client/amrecover.h:
  266.     * index/client/uparse.y:
  267.     * index/client/uscan.l:
  268.     Added clear extract list command.
  269.     
  270.     * index/client/set_commands.c (set_disk): 
  271.     Added code so working directory set to mount point.
  272.  
  273.     * index/client/extract_list.c:
  274.     If the last item on a tape list is deleted, the tape list
  275.     itself is now deleted from the extract list.
  276.  
  277.     * index/client/amrecover.c: 
  278.     * index/server/amindex.c:
  279.     If the server started up and found that the index dir doesn't
  280.     exist, then it exited immediately and the client got
  281.     informative message.  Corrected this so it is obvious what is
  282.     wrong to the user, since this is most likely to occur when
  283.     somebody is setting up for the first time and needs all the
  284.     help they can get.
  285.  
  286.     * server-src/amgetidx.c
  287.     Added patch from Pete Geenhuizen
  288.     (pete@gasbuggy.rockledge.fl.us) so that it works even when
  289.     remote shell is csh.
  290.  
  291.     * server-src/amcontrol.sh
  292.     * server-src/Makefile.in
  293.     Amcontrol is now parameterized like other scripts and run
  294.     through munge to generate installable version.
  295.  
  296.     * index/server/amindexd.c (main): 
  297.     Added code to set userid if FORCE_USERID set.
  298.  
  299.     * index/server/amindexd.c
  300.     Removed #define for full path of grep.  Assumed now to be on
  301.     path.
  302.  
  303.     * client-src/createindex-dump.c
  304.     * client-src/sendbackup-dump.c
  305.     * man/Makefile.in
  306.     Added patch from Philippe Charnier (charnier@lirmm.fr) so they
  307.     work when things are installed with version numbers.  This was
  308.     also reported by Neal Becker (neal@ctd.comsat.com).  Also patch
  309.     to set installed man page modes and create directory if
  310.     needed.
  311.  
  312.     * config/options.h-sunos4
  313.     Corrected definition for flex library.
  314.  
  315.     * server-src/amtrmidx.c
  316.     Added some pclose() commands, used remove() instead of
  317.     system("rm ..").  Problems reported by Pete Geenhuizen
  318.     (pete@gasbuggy.rockledge.fl.us) on a system with small ulimits
  319.     set.
  320.  
  321.     * index/server/amindexd.[ch]
  322.     * index/server/list_dir.c
  323.     * index/client/amrecover.c
  324.     * index/client/set_commands.c
  325.     * index/client/uparse.y
  326.     Changes developed with the help of Pete Geenhuizen
  327.     (pete@gasbuggy.rockledge.fl.us) to support disks specified by
  328.     logical names.  Also, now debug files generated by amrecover
  329.     include PID so multiple users can use amrecover simultaneously
  330.     and without file deletion permission problems.
  331.  
  332.     * config/config.h-hpux: 
  333.     * config/config-common.h:
  334.     * server-src/amgetidx.c:
  335.     Changes from Neal Becker re remote shell, making it a
  336.     configuration parameter.
  337.  
  338.     * config/options.h-sunos4
  339.     Had -Lfl instead of -lfl
  340.     
  341.  
  342.  
  343. CHANGES FROM AMINDEX-0.1
  344. ------------------------
  345.  
  346.     * index/client/uscan.l: 
  347.     added support for abbreviated date specs
  348.  
  349.     * index/client/amrecover.c (guess_disk): 
  350.     guess_disk got disk_path wrong if mount point other than / (as
  351.     subsequently pointed out by Eir Doutreleau <ed@cti.ecp.fr>)
  352.     
  353.     * server-src/amtrmidx:
  354.     Added amtrmidx which removes old index files.
  355.  
  356.     * index/client:
  357.     Added a pwd command
  358.  
  359.     * server-src/amgetidx.c (main): 
  360.     Added use of CLIENT_LOGIN username on r commands.  (as pointed
  361.     out by Eric Payan <Eric.Payan@ufrima.imag.fr>)
  362.  
  363.     * server-src/amgetidx.c:
  364.     Bug: It was copying from all clients irrespective of whether
  365.     the client was configured for indices.  A '}' in the wrong
  366.     place.
  367.  
  368.     * server-src/amgetidx.c: 
  369.     Removed user configuration section.  Instead include amindexd.h
  370.     to get information.
  371.  
  372.  
  373.  
  374. CHANGES/ADDITIONS TO 2.3.0
  375. --------------------------
  376.  
  377. common-src/conffile.[ch]
  378.  
  379. - added "index" as a valid option
  380.  
  381.  
  382. server-src/driverio.c
  383.  
  384. - added code to optionstr() to write "index" into option string
  385.  
  386.  
  387. client-src/sendback-dump.c
  388.  
  389. - added code to generate index if requested.
  390.  
  391. client-src/indexfilename.[ch]
  392. client-src/createindex-dump.c
  393.  
  394. - code to generate index.
  395.  
  396. client-src/Makefile.in
  397.  
  398. - a new target.  Another file for sendbackup-dump
  399.  
  400. config/config-common.h
  401.  
  402. - added def of restore.
  403.  
  404.  
  405.  
  406.  
  407. KNOWN BUGS
  408. ----------
  409.  
  410. - Empty directories don't get into the listing for a dump (at all dump
  411. levels).
  412.  
  413. - When amrecover starts up, it tries to guess the disk and mount point
  414. from the current directory of the working system.  This doesn't work
  415. for disks specified by logical names, nor when an automounter is being
  416. used, or a link is in the path.
  417.  
  418.  
  419. Alan M. McIvor
  420. 11 March 1997
  421.